;;
;;; matts-utils-readme.text
;;;


================================================================
Purpose ========================================================
================================================================
Describes the files in matts-utils-21jul92.sea.hqx, a collection of
useful MCL utilities. File names in this file are marked with "####" (no
quotes).


================================================================
Status =========================================================
================================================================
Released.

Copyright © 1990-92 Matthew Cornell. All Rights Reserved. Send
bugs, comments, questions, and fixes to cornell@cs.umass.edu.

Programming Style Note: The style in my newer files reflects my adoption
of the "Hungarian" naming standard. This standard is described in Byte's
August 1991 issue (Volume 16, Number 8), starting on p.131. Briefly,
variables names start with their base type, which is followed by
qualifiers. In my adaptation to Lisp I use these base types: l - list,
str - string, pn - pathname, ns - namestring, char - character, sym -
symbol, fcn - function, f - flag (boolean), macptr - macptr, p - macptr,
h - handle, etc. Function optionally names start with the type returned,
describe their action, and optionally end with the type(s) passed. Some
examples:

F-CAN-RECEIVE-DROP - A function that returns non-nil when the object can
                     receive a drop.
FONT-SPEC-STRING-OFDI - Returns the font-spec used for printing strings.
                        Passed an object-fred-dialog-item (OFDI).

L-STR-OBJ-OFDI-IN-RANGE - Returns a list of strings and objects in the
                          passed object-fred-dialog-item and passed range.


================================================================
Change history =================================================
================================================================
14-Mar-92 mc	Created.
13-Apr-92 mc	Updated for new .hqx name.
21-Jul-92 mc	matts-utils-21jul92.sea.hqx includes these changes:
		 pict-dialog-item.lisp      -  Updated
		 progress-indication.lisp   -  Updated
		 resource-utils.Lisp        -  Updated with compatibility break
		 save-all-fred-windows.lisp -  New
03-Aug-92 mc	matts-utils-3Aug92.sea.hqx includes these changes:
		 cl.lisp - New
		 drag-gray-region-lisp.lisp - New
		 object-dropper.lisp - New
		 object-fred-dialog-item.lisp - New
		 progress-indication.lisp - Updated
08-Sep-92 mc	matts-utils-8Sep92.sea.hqx includes these changes:
		 drag-gray-region-lisp.lisp	- Updated
		 draw-arrow.lisp		- New
		 f-pt-in-scroll.lisp		- New
		 get-input-of-type.lisp		- New
		 object-dropper.lisp		- Updated
		 object-FDI-drop-glue.lisp	- New
		 object-FDI-mouse-copy-glue.lisp - New
		 object-fred-dialog-item.lisp	- Updated
		 outline-window.lisp		- New
		 pict-dialog-item.lisp		- Updated
		 progress-indication.Lisp	- Updated
		 resource-utils.Lisp		- Updated
		 sound-scrap.lisp		- New
		 when-strings.lisp		- New		 


#### cl.lisp
Defines the cl (compile-load) function which is a simpler alternative for
managing a system's files than defsystem. Abides by the KISS (Keep It
Simple, Silly) philosophy.

#### compare-windows.lisp
Defines a simple but useful functionality that does a
character-by-character compare of the top two FRED windows.

#### drag-gray-region-lisp.lisp
Defines a LISP-level drag-gray-region function. Replaces
drag-gray-region.lisp with a cleaner, simpler function.

#### draw-arrow.lisp
Defines the draw-arrow function. Created from seth@aic.hrl.hac.com's source.

#### fred-keyboard-macros.lisp
Defines functions and command bindings to do simple FRED keyboard macro
recording.

#### f-pt-in-scroll.lisp
Defines f-pt-in-scroll, a handy addition to sequence-dialog-items and
fred-windows. Thanks to holz@urz.unibas.ch (Dieter Holz) for help with
the fred-window version.

#### get-input-of-type.lisp
Defines the get-input-of-type function.

#### object-dropper.lisp
Defines a extensible object drop functionality. *Very* handy. Examples
extend FRED to handle dropping by inserting strings, extend
object-fred-dialog-items (see below) to insert objects, and define a
function button-dialog-item that runs a function on objects dropped on it.

(export '(F-CAN-RECEIVE-DROP INVERT-DROP-HIGHLIGHT RECEIVE-DROP
          MACPTR-REGION-GLOBAL TRACK-MOUSE-FOR-DROPPING))

#### object-fred-dialog-item.lisp
Defines the object-fred-dialog-item subclass of fred-dialog-item, which
knows how to display strings and non-string objects. Strings are displayed
in a user-selected font different from non-string objects. A non-string
object's text is selected and deleted as a whole when users select or
delete parts of its text. Examples extend Apple's mouse-copy.lisp example
file so that command-clicking on inspector and other windows adds a "link"
to the clicked-on object in object-fred-dialog-items. *Very handy, too.

(export '(OBJECT-FRED-DIALOG-ITEM FONT-SPEC-STRING-OFDI FONT-SPEC-NON-STRING-OFDI
          ADD-LINK EDIT-L-DATA L-STR-OBJ-OFDI L-STR-OBJ-OFDI-SELECTED
          L-STR-OBJ-OFDI-IN-RANGE *L-OBJECT-GIVEN*))

#### object-FDI-drop-glue.lisp
Tell object-fred-dialog-items how to start drops. Since
object-fred-dialog-item is a subclass of fred-dialog-item they already know
how to receive drops via the code at the bottom of
object-fred-dialog-item.lisp .

#### object-FDI-mouse-copy-glue.lisp
Defines functions to make the "MOUSE-COPY" example do links.

#### outline-window.lisp
Defines a Finder-like hierarchy display. Outline-window instances display
hierarchies.

#### pict-dialog-item.lisp
Defines the pict-dialog-item class of dialog items. This class implements a
picture button similar to icon-dialog-items.

#### progress-indication.lisp
Defines a simple but useful functionality that defines
WITH-PROGRESS-INDICATION and PROGRESS-STEP which provide a uniform way to
note incremental progress during long operations. Fondly inspired by
Symbolics' noting-progress mechanism.

#### resource-utils.lisp
Defines a LISP-style error-checked interface to the Resource Manager. The
function definitions are organized as in Inside Macintosh VI.

#### save-all-fred-windows.lisp
Defines save-all-fred-windows and installs it on *file-menu*.

#### select-rectangle.lisp
Defines a LISP-level select-rectangle function.

#### sound-fun.Lisp
Defines the sound-dialog dialog subclass that has a sound associated with
each of its four buttons. Also, pressing one of the keys 1-4 will play the
corresponding button's sound.

#### sound-scrap.lisp
Created from Apple's Pict-Scrap.Lisp, defines a scrap-handler for scraps of
type :|snd | .

#### when-strings.lisp
Defines functions for decoding when-strings, which are strings encoding
possibly repeating times and dates.
